.\" vim: set ft=nroff .\"
.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
.\" #
.\" #              C E D A R
.\" #          S O L U T I O N S       "Software done right."
.\" #           S O F T W A R E
.\" #
.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
.\" #
.\" # Author   : Kenneth J. Pronovici <pronovic@ieee.org>
.\" # Project  : banner
.\" # Purpose  : Manpage for the banner program
.\" #
.\" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
.TH banner "1" "Mar 2024" "Banner" "Kenneth J. Pronovici"
.SH NAME
banner \- prints a short string to the console in very large letters
.SH SYNOPSIS
.B banner
\fIstring\fR
.SH DESCRIPTION
.PP
This is a classic-style banner program similar to the one found in Solaris or
AIX in the late 1990s.  It prints a short string to the console in very large
letters.
.PP
Banners that do not fit in the terminal will be truncated.  If $COLUMNS is
exported in the environment, it is taken to be the width of the terminal.  If
$COLUMNS is not exported, and TIOCGWINSZ is available on the platform, then its
idea of the terminal size is used.  Otherwise, a terminal width of 80
characters is assumed.  
.PP
Usage is straightforward.  For instance, a single word is printed like this:
.PP
   > banner ken
   
   #    #  #######  #     #
   #   #   #        ##    #
   #  #    #        # #   #
   ###     #####    #  #  #
   #  #    #        #   # #
   #   #   #        #    ##
   #    #  #######  #     #
.PP
Multiple arguments are printed on separate lines:
.PP
   > banner one two  
   
   #######  #     #  #######  
   #     #  ##    #  #        
   #     #  # #   #  #        
   #     #  #  #  #  #####    
   #     #  #   # #  #        
   #     #  #    ##  #        
   #######  #     #  #######  
      
   
   #######  #     #  #######  
      #     #  #  #  #     #  
      #     #  #  #  #     #  
      #     #  #  #  #     #  
      #     #  #  #  #     #  
      #     #  #  #  #     #  
      #      ## ##   ####### 
.PP
To get a single long line containing whitespace, you must quote the string:
.PP
   > banner "one two"
   
   #######  #     #  #######        #######  #     #  #######  
   #     #  ##    #  #                 #     #  #  #  #     #  
   #     #  # #   #  #                 #     #  #  #  #     #  
   #     #  #  #  #  #####             #     #  #  #  #     #  
   #     #  #   # #  #                 #     #  #  #  #     #  
   #     #  #    ##  #                 #     #  #  #  #     #  
   #######  #     #  #######           #      ## ##   #######  

.SH COMPATIBILITY
.PP
From time to time, people assert that this program is buggy because it
doesn't do something that some other banner implementation does.  The
behavior of the program is based on what I saw on Solaris and AIX systems
at the time I wrote it in the late 1990s.  I make no claims that the
behavior is identical to that of any other contemporary system, especially
any non-free system that I may or may not have access to. 
.PP
If you don't like the behavior, you can either submit a patch, or you can
use an alternative program such as figlet.  I am always happy to accept
patches, and I promise to integrate patches promptly if provided.  So far,
no one who's complained has bothered to provide any patches, so the
behavior remains the same.
.SH AUTHOR
Written by Kenneth J. Pronovici <pronovic@ieee.org>.
.SH COPYRIGHT
Copyright (c) 2000\-2004,2007,2013,2014,2020,2024 Kenneth J. Pronovici
.br
This is free software; see the source for copying conditions.  There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
